Builder

Declaratively build and visualize applications and business processes.

Introduction

Usage

When should you think about using a builder? Start, as, always, with the user. If users will be doing one or more of these things, there could be a builder in your future:

• Working with WYSIWYG (“what you see is what you get”) declarative elements that can be added with clicks and customized with forms
• Designing a business process on a blank canvas
• Creating and defining a series of logical actions that result in different outputs
• Defining the relationship of one element to another—for example, in a workflow or visual layout
• Saving and tracking multiple drafts or versions

If a builder isn’t a good fit, consider using another framework, such as a modal wizard, Channel Studios on Marketing Cloud, an expression or formula builder, or a series of filters. If you’re working with templates, consider forms or studio editors.

Workflow

Where to Launch a Builder

Are you an admin or developer designing for your Salesforce users? If so, any builder you design should live in Setup. Make sure that your builder can be accessed from a Setup page and from the Setup navigation.

Outside of Setup, make builders accessible from a relevant record detail page or app landing page. For example, make a builder that creates a new workflow for email engagement accessible from both the email engagement record detail page and the email engagement app page.

Record Information: Names, Versions, and Statuses

When you’re ready to launch a builder, the journey often starts on a record list page, where you’ll find a clear summary of file names, versions, and statuses. Display this information in the builder as well. Record information must be displayed in three areas:

Record List

Display the file name, version, and status in a list among other similar builders.

Record Detail

For each record, provide a dedicated view of its file name and version(s). This orients users without making them return to the builder.

Builder Header

This header must display the builder name, file name, and save status. Read more here.

Saving Builder Records

When working in a builder, users tend to save their changes often. Some builders also let users activate, run, or publish.

Saving is a server-side snapshot of an object and its state. Note that saving does not inherently equal approval to push an object for activation or publication. These are two separate actions that do two different things. If saving does activate/publish a file or execute a process, be sure to explicitly call this out to the user.

When and how can I save my builder objects?

• Use a Save button to initiate a server-side save of the entire object.
• When a builder uses manual saving, users should be allowed to save even when their work contains errors. See Error and Warning Popovers for more information on messaging.
• When a save also triggers activation/publication, allow the file to be saved without push. Alert the user to errors blocking activation/publication.

What about object versions?

• Builders may allow for object versioning. If your builder allows versioning, offer users the ability to clone or copy objects through a Save As command.
• If a builder autosaves (and creates auto-versions for each save), batch changes in an autosave and a new version. And always give users an easy way to view and revert to previous versions.

How does saving work when multiple records are open?

• Multiple records can be viewed simultaneously in new browser windows or tabs.
• An explicit save affects only the record currently in focus—not other open records.
• When closing a browser window with any unsaved records, users should see a warning that they will lose all unsaved changes.

Autosave

No Salesforce builders currently use autosave. However, here are four principles to consider if and when the feature becomes an option.

• Confidence: Make clear what is and isn’t saved at all times. Can an autosave offer the trust of an explicit save button?
• Simplicity: How are previous versions presented? Reinstated? What is a simple, easy, and on-pattern way for users to perform these actions?
• Data: Where do autosave versions live? Do they affect a user’s data limits? Are both users and Salesforce prepared to deal with the data implications?
• Performance: What effect will constant saving have on performance? Are the benefits of autosaving and versioning enough to outweigh any lag?

Indicating Save Status

Clearly communicate save status, but without overwhelming users or drawing focus from the task at hand.

• Show status with an inline indicator next the builder header action buttons: Saving... (save in progress), Saved, or Saved [time] (indicating when the file was last saved).
• Don’t use toasts or banners for save messages. When users save often, toasts can be disruptive. Banners are reserved for systemwide messages.

Activating or Publishing a Builder

Most builders separate save functionality from publication/activation, allowing users the freedom to edit without affecting runtime or live business processes.

Place the Activate or Publish action at the right side of the builder toolbar, with other action buttons. If the needs or technical limitations of your builder make that difficult, you may also place this action on the Builder Home or Record Overview pages.

Activation and deactivation are significant milestones—use a toast to notify users of success, failure, and related warnings or errors.

Exiting a Builder

To exit a builder, users can close the browser window or hit the back button in the Builder Header. They should be brought back to the page initially used to launch the builder.

Builder Parts

A builder is made up of a set of parts, some commonly used and others unique to specific builders. Lightning Design System has markup ready to use as component blueprints for some builder parts. Parts without component blueprints are covered in the next section, Builder Elements.

All builders must have a builder header and a toolbar. These make up the basic frame that indicates to users that they are in a builder.

Logic builders have a specific set of required parts: a canvas, workflow connectors, and nodes. Some examples of logic builders are Flow Builder, Engagement Studio, Journey Builder, Process Builder.

In addition to required parts, builders can have one or more optional panels, modals, and popovers to configure items on the canvas. There’s also an optional zoom tool.

Builder Elements

Canvas

The canvas is the open workspace and main working area of your builder layout. It should occupy the bulk of UX real estate. Here users can add and manipulate nodes, connectors, and other components.

Connectors

Connectors are lines that connect nodes to illustrate a path. They represent relationships and movements between nodes. Use the badge component to label connectors.

• Use connectors to connect to nodes horizontally or vertically at 0°, 90°, 180°, or 270° angles.
• Don’t use connectors without horizontal or vertical alignment (i.e., avoid 45° and freeform connectors).

In testing mode, a user can choose a path through a workflow, then see it reflected in color and line-weight changes to the connector path.

Nodes

Nodes are the building blocks of a workflow. Each one represents an action.

• Use paired shapes and colors to represent each possible action and process step.
• Don't use different colors and shapes to represent the same state.

Consistency is important here: Keep node shapes and colors consistent across actions, and standardize type color, size, and spacing.

Each node must have a name label. Nodes may also include an icon inside the node, a description below the name, and a link below the description. Labels can be up to 132 pixels across. You can also add icons to differentiate related functions, such as Start and End.

Node Deletion Behavior

Across Salesforce, the trashcan icon denotes removal of an element, while the “x” icon denotes closing or dismissing an element. Use the trash can icon to allow removal of a workflow node when the user hovers over it.

Use a 44x44 pixel touch target for mobile web.

Node Error Behavior

Across Salesforce, the ban icon denotes errors. Use the ban icon in the upper left corner of the node, and highlight the affected node with an outline.

When errors are identified and appear in the Error Popover, highlight affected node(s). Allow the user to navigate between elements, to address the node that is causing the error.

Use a 44x44 pixel touch target for mobile web.

Builder Component Blueprints

Builder Header

See the Builder Header component blueprint for implementation information

Overview

Every builder needs a builder header, which contains basic navigation elements. It also shows the builder type and content name.

Usage

A builder header should span the width of the viewport (the viewable area in a browser), and should be used in full-screen mode. Navigation to other areas of the builder may be placed between the app name and document name.

Designing for business users? Use the record header component as your builder header. Put it below the global header and global navigation.

Action Toolbar Variant

The action toolbar lives below the builder header. It’s locked in place, and has a width of 1024 pixels.

This toolbar houses buttons that affect the builder as whole—classics like Save, Undo, Copy, and Zoom. Keep your action toolbar lean and mean, with a maximum of five buttons. For more than that, use an overflow menu.

About Messaging in the Toolbar

Like in the Save and Error and Warning Popover sections, the toolbar is also used to convey important messages to users about builder status (save success/failure and related warnings and errors).

Button Group

See the Button Group component blueprint for implementation information

Overview

Use a Button Group to create a zoom tool to allow users to magnify or minimize the screen view, zooming in or out on items viewed.

The preferred mode is incremental zoom, a button group using the minus, plus, and expand and contract icons. Users can click to incrementally zoom out (-) or zoom in (+), and can toggle between zoom-to-fit (contract) and zoom-to-100% (expand) views of the canvas.

Usage

When first opening a record, users view the canvas at 100%, with the first node in a workflow placed at the upper left of the canvas. Zooms in and out are based on the current center point of the canvas in view; users can pan to shift the center point.

If a user clicks on a node or other canvas element, the view centers on that element and that element becomes the center point of any zooming action.

• Place the zoom button group inside the canvas; we recommend the bottom right of the canvas, as shown below.
• Set canvas zoom speed at 250ms per increment.
• When maximum and minimum zoom threshold is reached, disable the corresponding - or + button.

Toggle Zoom Variant

Toggle zoom lets users switch between two views, 100%, and zoom-to-fit. If zoom functionality is controlled in the toolbar, use toggle zoom.

Panel

See the Panel component blueprint for implementation information

Overview

Panels are builder tool chests, presenting momentary tasks and supplemental information associated with the current builder.

Usage

Use a panel to host functions pertinent to the current builder. Panels have a hierarchy from left to right. The left panel must host the primary functions and tasks to be used in the builder. Once tasks are added to the Canvas, they can be interacted with. The right panel must host the secondary functions, plus supplemental information to be used when a canvas item is active.

Panel Navigation

Use a button icon in the builder header toolbar to toggle panel visibility.

Use a drill in to show a second level of builder content in a panel.

Dialog and Reflow Variants

By default, panels are nonmodal dialogs that float above the canvas content on a raised z-index. Use the default dialog panel in a builder if the content in the panel takes temporary focus.

Alternatively, panels can open as drawers, reflowing the screen content to share screen real estate. Use a reflow panel if the panel content needs to share focus with the canvas—for example, where the canvas needs to be referenced when interacting with the panel’s content.

Popover

See the Popover component blueprint for implementation information

Overview

Popovers are nonmodal dialogs that give the user contextual information and actions on canvas elements, and message users about errors and warnings.

Usage

A popover gives the user information relevant to whatever it points to on the builder canvas. Each popover has a linked trigger element, like a node; when clicked, it opens the popover and either highlights relevant information or provides actions against the trigger element.

All popover messages must be:

• Dynamically generated, based on builder file contents (no static messages here)
• Actionable (the user can take action against the element)

Error Popover Variant

All errors that prevent a builder from being saved should appear in an error popovers based in the toolbar. Error messages include header text on a red background; footers are optional.

Warning Popover Variant

All issues that prevent a builder from being activated or published, or prevent runtime, should appear in warning popovers based in the toolbar. Warning popovers include header text on a gold background; footers are optional.

Click to Create Variant

This popover variant lets users build workflows by selecting nodes, connectors, and other workflow elements from its menu. Note that the “add” icon rotates 45° to look like a “close” icon when the popover is open, in addition to other animation changes.

List Menu

The list menu layout presents next-step options visually.

Visual Menu

The tile menu layout lets users quickly select from a limited number of options.

Drill In

For longer, nested option menus, add a drill in and a search input. A back button will let users navigate branches of the original menu.

Test Mode Variant

In manual workflow testing, users evaluate paths for logic and flow. At each decision point, a popover offers the user options to choose from (for example, an audience group or an event). To present two options, use two buttons side by side. For three to four options, stack the option buttons. For five or more options, add a scroll bar.

Modal

See the Modal component blueprint for implementation information

Overview

Modals display content in a layer above the app. They’re used for messaging, setup, and other wizards, and for creating or editing records.

Usage

You can use both modals and panels in a builder. In general, panels are preferred over modals, though each has its uses. Use this decision matrix to guide your choices.

When to Use Panels or Modals